Best Practice
示例说明
1 | Summarize changes in around 50 characters or less |
1.Separate subject from body with a blank line
Though not required, it’s a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description.
The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git.
For example, Git-format-patch(1) turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the body.
Firstly, not every commit requires both a subject and a body. Sometimes a single line is fine, especially when the change is so simple that no further context is necessary. For example:
1 | Fix typo in introduction to user guide |
Nothing more need be said; if the reader wonders what the typo was, she can simply take a look at the change itself, i.e. use git show or git diff or git log -p.
If you’re committing something like this at the command line, it’s easy to use the -m option to git commit:
1 | $ git commit -m"Fix typo in introduction to user guide" |
However, when a commit merits(vt值得) a bit of explanation and context, you need to write a body. For example:
1 | Derezz the master control program |
In any case, the separation of subject from body pays off when browsing the log. Here’s the full log entry:
1 | $ git log |
And now git log –oneline, which prints out just the subject line:
1 | $ git log --oneline |
git shortlog, which groups commits by user, again showing just the subject line for concision:
1 | $ git shortlog |
There are a number of other contexts in Git where the distinction between subject line and body kicks in—but none of them work properly without the blank line in between.
2.Limit the subject line to 50 characters
50 characters is not a hard limit, just a rule of thumb. Keeping subject lines at this length ensures that they are readable, and forces the author to think for a moment about the most concise way to explain what’s going on.
在github上,commit message列表会显示第一行title信息,但是超过72个字符的commit message在显示的时候会被截断。
3.Capitalize the subject line
Correct Example
- Accelerate to 88 miles per hour
Incorrect Example
- **accelerate to 88 miles per hour**
4.Do not end the subject line with a period
Correct Example
- Open the pod bay doors
Incorrect Example
- Open the pod bay **doors.**
5. Use the imperative mood in the subject line
Imperative mood just means “spoken or written as if giving a command or instruction”. A few examples:
- Clean your room
- Close the door
- Take out the trash
The imperative can sound a little rude; that’s why we don’t often use it. But it’s perfect for Git commit subject lines. One reason for this is that Git itself uses the imperative whenever it creates a commit on your behalf.
For example, the default message created when using git merge reads:
1 | # 1.merge |
So when you write your commit messages in the imperative, you’re following Git’s own built-in conventions. For example:
- Refactor subsystem X for readability
- Update getting started documentation
- Remove deprecated methods
- Release version 1.0.0
Writing this way can be a little awkward at first. We’re more used to speaking in the indicative mood, which is all about reporting facts. That’s why commit messages often end up reading like this:
- Fixed bug with Y
- Changing behavior of X
And sometimes commit messages get written as a description of their contents:
- More fixes for broken stuff
- Sweet new API methods
To remove any confusion, here’s a simple rule to get it right every time.
A properly formed Git commit subject line should always be able to complete the following sentence:
If applied, this commit will your subject line here
For example:
- If applied, this commit will refactor subsystem X for readability
- If applied, this commit will update getting started documentation
- If applied, this commit will remove deprecated methods
- If applied, this commit will release version 1.0.0
- If applied, this commit will merge pull request #123 from user/branch
Notice how this doesn’t work for the other non-imperative forms:
- If applied, this commit will fixed bug with Y
- If applied, this commit will changing behavior of X
- If applied, this commit will more fixes for broken stuff
- If applied, this commit will sweet new API methods
Remember: Use of the imperative is important only in the subject line. You can relax this restriction when you’re writing the body.
6. Wrap the body at 72 characters
Git never wraps text automatically. When you write the body of a commit message, you must mind its right margin, and wrap text manually.
The recommendation is to do this at 72 characters, so that Git has plenty of room to indent text while still keeping everything under 80 characters overall.
A good text editor can help here. It’s easy to configure Vim, for example, to wrap text at 72 characters when you’re writing a Git commit. Traditionally, however, IDEs have been terrible at providing smart support for text wrapping in commit messages (although in recent versions, IntelliJ IDEA has finally gotten better about this).
7.Use the body to explain what and why vs. how
This commit from Bitcoin Core is a great example of explaining what changed and why:
1 | commit eb0b56b19017ab5c16c745e6da39c53126924ed6 |
Take a look at the full diff and just think how much time the author is saving fellow and future committers by taking the time to provide this context here and now. If he didn’t, it would probably be lost forever.
In most cases, you can leave out details about how a change has been made. Code is generally self-explanatory in this regard (and if the code is so complex that it needs to be explained in prose, that’s what source comments are for). Just focus on making clear the reasons why you made the change in the first place—the way things worked before the change (and what was wrong with that), the way they work now, and why you decided to solve it the way you did.
8. Tips
Learn to love the command line. Leave the IDE behind.
Import Book:https://git-scm.com/book/en/v2